PicComment

PicComment
Header:	Quickdraw.h		Carbon status:	Supported

Inserts a picture comment into a picture that you are defining or into your printing code.

void PicComment (
    SInt16 kind, 
    SInt16 dataSize, 
    Handle dataHandle
);

Parameter descriptions

kind: The type of comment.
dataSize: Size of any additional data passed in the dataHandle parameter. If no additional data is used, specify 0 in this parameter.
dataHandle: A handle to additional data, if used. If no additional data is used, specify NULL in this parameter.

DISCUSSION

When used after your application begins creating a picture with the OpenCPicture (or OpenPicture) function, the PicComment function inserts the specified comment into the Picture structure. When sent to a printer driver after your application uses the PrOpenPage function, PicComment passes the data or commands in the specified comment directly to the printer.

Picture comments contain data or commands for special processing by output devices, such as printers.

Usually printer drivers process picture comments, but applications can also do so. For your application to process picture comments, it must replace the StdComment function pointed to by the commentProc field of the CQDProcs or QDProcs structure, which in turn is pointed to by the grafProcs field of a CGrafPort or GrafPort structure. The default StdComment function provided by QuickDraw does no comment processing whatsoever. You can use the SetStdCProcs function to assist you in changing the CQDProcs structure, and you can use the SetStdProcs function to assist you in changing the QDProcs structure.

If you create and process your own picture comments, you should define comments so that they contain information that identifies your application (to avoid using the same comments as those used by Apple or by other third-party products). You should define a comment as an ApplicationComment comment type with a kind value of 100. The first 4 bytes of the data for the comment should specify your application’s signature. You can use the next 2 bytes to identify the type of comment—that is, to specify a kind value to your own application.

Suppose your application signature were 'WAVE', and you wanted to use the value 128 to identify a kind value to your own application. You would supply values to the kind and data parameters to PicComment as follows:

kind = 100; data = 'WAVE' [4 bytes] + 128 [2 bytes] + additional data [n bytes]

Your application can then parse the first 6 bytes of the comment to determine whether and how to process the rest of the data in the comment. It is up to you to publish information about your comments if you wish them to be understood and used by other applications.

SPECIAL CONSIDERATIONS

These former picture comments are now obsolete: SetGrayLevel, ResourcePS, PostScriptFile, and TextIsPostScript.

The PicComment function may move or purge memory.

AVAILABILITY

Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.1 or later.